安卓开发文档翻译:实现谷歌云消息服务器,Implementing GCM Server
谷歌云消息系统的服务器端,由2个组件构成:
•. 谷歌提供 的 谷歌 云消息连接服务器 ,接收来自某个第三 方服务器的消息,然后将它们发送给某个设备 上运行着的启用了谷歌云消息功能的安卓应用程序("客户端应用程序")。例如,谷歌提供 了针对 超文本传输协议 和 云连接服务器 ( 可扩展消息及状态协议 )的连接服务器。
•. 一个 第三 方应用程序服务器 ,这个需要由妳自己来实现。 这个应用程序服务器,通过所选择的谷歌云消息连接服务器,将数据发送给启用了谷歌云消息功能的安卓应用程序。
妳可按照以下基本步骤来实现妳的第三方应用程序服务器:
•. 作出决定 ,妳想要使用哪 种 谷歌云消息连接服务器。注意 ,如果妳想要从客户端程序中发送上行消息的话,则,妳必须使用云连接服务器。 欲知更多细节,则参考 选择 一个谷歌云消息连接服务器 。
•.作出决定,妳想要如何实现妳的应用程序服务器。例如:
•.如果妳决定使用超文本传输协议的连接服务器,则,妳可以使用已有的谷歌云消息服务器辅助库,且参考示例程序来实现妳的应用程序服务器。
•. 如果 妳决定使用可扩展消息及状态协议连接服务器,则, 妳可以使用所提供的 蟒蛇( Python ) 或 爪哇( Java ) 的风味 ( Smack ) 示例程序 来作为一个起点。
•.注意,谷歌应用引擎(Google AppEngine)不支持与云连接服务器建立连接。
在一个完整的谷歌云消息系统中,需要实现一个客户端和一个服务器。欲知更多关于如何实现客户端 的信息,则阅读 实现谷歌 云消息的客户端 。
目前,谷歌云消息提供了两种连接服务器: 超文本传输协议 和 云连接服务器 ( 可扩展消息及状态协议 ) 。 妳可以单独使用其中的一种,或者两种都使用。云连接服务器的消息传送与谷歌云消息的超文本传输协议的消息传送之间有如下不同:
•.上行/下行消息
•.谷歌云消息的超文本传输协议服务器:只支持下行消息:从云端到设备。
•. 云连接服务器:上行及下行(设备到云端,云端到设备)。
•.异步消息
•.谷歌云消息的超文本传输协议服务器:第三方服务器以超文本传输协议的发送(POST )请求来发送消息,并且等待回复。这种机制是同步的,使得发送者会阻塞一段时间才能发送下一条消息。
•.云连接服务器:第三方应用程序服务器通过一个持久的可扩展消息及状态协议连接来连接到谷歌的系统,并与所有的设备之间以满速收发消息。云连接服务器异步地发送确认或失败通知(它们是特殊的以爪哇脚本对象标记(JSON)形式编码的可扩展消息及状态协议消息,表示确认(ACK)及否认(NACK))。
•.爪哇脚本对象标记(JSON)
•.谷歌云消息的超文本传输协议服务器:爪哇脚本对象标记消息是以超文本传输协议的发送请求的形式发送的。
•. 云连接服务器:爪哇脚本对象标记消息被封装在可扩展消息及状态协议消息里。
在妳开始编写具有谷歌云消息功能的安卓应用程序之前,妳必须已经有了一个满足以下要求的应用程序服务器:
•.可与妳的客户端通信。
•.能够向谷歌云消息服务器发送正确的请求。
•. 能够使用 指数补偿 算法正确 地处理请求以及重新发送它们。
•.能够储存应用编程接口(API)密钥和客户端的注册编号。应用编程接口密钥需包含在用于发送消息的发送请求的协议头中。
•.能够生成消息编号,以便唯一地标识它所发送的每条消息。对于每个发送者编号,其所发送的消息编号应当是唯一的。
第三方应用程序服务器发送消息时,要经过以下过程:
1.应用程序服务器向谷歌云消息服务器发送一条消息。
2.如果对应的设备处于离线状态,则谷歌将该消息加入到队列中并且存储起来。
3.当该设备处于在线状态时,谷歌将对应的消息发送给该设备。
4.在设备上,系统会使用意图(Intent)广播来向指定的安卓应用程序发送这条消息,该意图中设置了适当的权限,使得只有目标安卓应用程序才能够接收到该消息。这将会唤醒对应的安卓应用程序。目标安卓程序不需要预先处于运行状态,同样可以接收到该消息。
5.对应的安卓应用程序处理该消息。
下一小节说明了在发送消息的过程中所需要满足的基本要求。
必需的。当妳的应用程序服务器通过谷歌云消息发送一条消息时,必须指定一个发送目标。
对于超文本传输协议的服务器,妳必须以下面任一种方式来指定发送目标:
•. registration_ids :用来 向 1 个或更多设备 (最多1000 个 ) 发送消息。 当妳向多个注册编号发送同一条消息时,该消息被称为多播消息。
•. notification_key :用来 向同一个用户拥有的多个设备发送消息。
对于云连接服务器(可扩展消息及状态协议):
•.妳必须将发送目标放置到“目标”("to")字段中,该字段可包含单个的注册编号或者某个通知密钥。云连接服务器不支持多播消息。
可选 。如果 妳想在消息中包含一个负载的话,则应当使用 data 参数 来包含负载。这对于超文本传输协议服务器和云连接服务器都有效。
下表中列出了第三方服务器向连接服务器发送的爪哇脚本对象标记消息中可使用的参数。参考“哪种服务器支持此参数”一列,以了解哪种服务器支持当前所说的那个参数。
字段 |
说明 |
哪种服务器支持此参数 |
to |
在云连接服务器中,替代 registration_ids ,用来指定消息的接收者。它的值必须是一个注册编号。这个值是一个字符串。此参数是必须的。 |
云连接服务器 |
message_id |
在云连接服务器中,唯一地标识同一个可扩展消息及状态协议中 的每条消息。这个值是一个字符串,唯一地标识与之相关的消息。是必须参数。 |
云连接服务 器 |
message_type |
在云连接服务器中,用于表示一种特殊的状态消息,一般是由系统发送的。但是,妳的应用程序服务器也可以使用这个参数来向云连接服务器回复‘确认’或‘否认’消息。欲知更多信息,则阅读 云连接服务器 。这个值是一个字符串。可选。 |
云连接服务器 |
registration_ids |
一个字符串数组,列出将会接收到这条消息的那些设备(它们的注册编号)。它必须包含最少1个、最多1000个注册编号。要发送一条多播消息的话,妳必须使用爪哇脚本对象标记。如果只是要向单个设备发送单条消息,那么,妳可以使用一个只包含了单个注册编号的爪哇脚本对象标记,或者使用纯文本(下文详述)。每个请求中都必须包含一个接收者——可以是一个注册编号、由注册编号组成的一个数组、或者是一个通知密钥( notification_key )。这个参数是必须的。 |
超文本传输协议服务器 |
notification_key |
一个字符串,将某个用户映射到与该用户关联的多个注册编号上去。这就使得第三方服务器可以向单个用户拥有的多个应用程序实例(一般是位于多个设备上)发送单条消息。第三方服务器可使用通知密钥( notification_key )作为某条消息的目标,而不使用单个注册编号(或多个注册编号组成的数组)。每个通知密钥( notification_key )中允许的最大成员个数为10。欲知更多细节,则阅读 用户通知 。这个参数是可选的。 |
超文本传输协议服务器。在云连接服务器中也支持这个特性,但是用法稍有不同,妳需要在“发送目标”("to")字段中指定这个通知密钥。 |
collapse_key |
一个任意的字符串(例如“有可用更新”("Updates Available")),用来在设备离线时将同一种类的消息分组到一起,这样,每个分组中只有最后一条消息会被发送给客户端。这是为了避免在手机重新上线时一次性向它发送过多的消息。注意,在传递消息时并不会确保消息之间的顺序,因此,“最后”一条消息不一定是应用程序服务器提交的最后一条消息。折叠键,也被称为
同步发送消息
。
|
云连接服务器、超文本传输协议服务器 |
data |
一个爪哇对象标记对象,它的字段即为要传递的消息的负载数据中的键值对。如果带有这个参数,则,负载中的数据会被包含到意图(Intent)中去,作为应用程序数据,并且其中的键会作为意图中对应的额外数据的名字。例如, "data":{"score":"3x1"} ,会使得意图中包含一个名为 score 的额外数据,其值为 3x1 。对于键值对的数量没有限制,但是对于整条消息的尺寸有限制(4kb)。其中的值可以是任意的爪哇对象标记对象,但是,我们建议使用字符串,因为,这些值最终是一定会被谷歌云消息服务器转换成字符串的。如果妳想要包含一些对象或者其 它的非字符串的数据类型(例如整数或逻辑值)的话,则,妳需要自己将它们转换成字符串。另外需要注意,其中的键,不可以是保留字( from 或者别的以 google. 开头的词)。再把事情说得稍微复杂一点点,某些保留字(例如 collapse_key ),在技术上来讲,是允许放置在负载数据中的。但是,如果在请求中也包含有该保留字的话,那么,请求中的那个值会覆盖掉负载数据中的那个值。因此,不建议将本表中的那些字段名字用作负载数据中的键,尽管从技术上是允许的也不要这么做。可选。 |
云连接服务器、超文本传输协议服务器 |
delay_while_idle |
如果包含这个参数,则表示,当设备处于空闲(idle)状态时,不应当将消息立即传递给该设备。服务器会等待设备进入活跃状态,然后,只发送每个折叠键( collapse_key )对应的最后一条消息。默认值是假( false ),并且必须是一个爪哇脚本对象标记的逻辑值。可选。 |
云连接服务器、超文本传输协议服务器 |
time_to_live |
当设备处于离线状态时,应当在谷歌云消息存储系统中将该消息保留多长时间(以秒为单位)。可选(默认的生存时间是4个星期,必须设置为一个爪哇脚本对象标记的数值)。 |
云连接服务器、超文本传输协议服务器 |
restricted_package_name |
一个字符串,包含着妳的应用程序的软件包名字。如果设置了这个值,则,消息只会被传递给匹配了这个软件包名字的注册编号。可选。 |
超文本传输协议服务器 |
dry_run |
如果包含了这个值,则允许开发者在不真正发送消息的情况下测试他/她们发送的请求。可选。默认值是假( false ),必须设置为一个爪哇脚本对象标记的逻辑值。 |
超文本传输协议服务器 |
如果 妳想测试妳所发送的请求(无论 是爪哇脚本对象标记还是纯文本 )而不真正向设备传递消息的话,则, 可以设置一个可选的超文本传输协议或爪哇脚本对象标记参数 dry_run ,将它 的值 设 为真( true )。 其结果会与不带这个参数时的结果几乎相同, 不同之处就是, 该消息不会被传递给目标设备。所以 ,对应的回复中,会包含有假的消息编号及多播字段。
如果妳是使用纯文本而不是使用爪哇脚本对象标记的话,则,消息的各个字段必须以超文本传输协议参数的方式放置在协议数据体中,并且其语法也稍有不同,以下详述:
字段 |
说明 |
registration_id |
必须包含将要接收这条消息的单个设备的注册编号。必须参数。 |
collapse_key |
与爪哇脚本对象标记模式相同(参考前一个表格)。可选。 |
data.<key> |
负载数据,其格式为,参数的名字前缀是 data. ,后缀是该值的键。例如, data.score=3x1 ,会使得意图中包含一个名为 score 的额外数据,其值为 3x1 。对于键值对的数量没有限制,但是对于整条消息的尺寸有限制。另外需要注意,其中的键,不可以是保留字( from 或者别的以 google. 开头的词)。再把事情说得稍微复杂一点点,某些保留字(例如 collapse_key ),在技术上来讲,是允许放置在负载数据中的。但是,如果在请求中也包含有该保留字的话,那么,请求中的那个值会覆盖掉负载数据中的那个值。因此,不建议将本表中的那些字段名字用作负载数据中的键,尽管从技术上是允许的也不要这么做。可选。 |
delay_while _idle |
应当用 1 或 true 来表示真( true ),其它的任意值都表示假( false )。可选。 默认值是假( false )。 |
time_to_live |
与爪哇脚本对象标记模式相同(参考前一个表格)。可选。 |
restricted_package_name |
与爪哇脚本对象标记模式相同(参考前一个表格)。可选。 |
dry_run |
与爪哇脚本对象标记模式相同(参考前一个表格)。可选。 |
当某个移动设备上安装的某个安卓应用程序接收消息时,将经历以下过程:
1.系统接收到传入的消息,如果其负载中有原始的键值对数据的话,则全部提取出来。
2. 系统 将这些键值对以额外数据的方式通过一个 com.google.android.c2dm.intent.RECEIVE 意图(Intent)发送给目标安卓应用程序。
3. 目标安卓应用 程序按照键来从 com.google.android.c2dm.intent.RECEIVE 意图中提取出原始数据,并且处理该数据。
参考每种连接服务器的文档,以了解关于如何处理回复的更多细节。
未知美人
城管是在被妖魔化吗?
Your opinionsHxLauncher: Launch Android applications by voice commands